Empty state

#Purpose

The EmptyState informs and guides users when no content is available within a container. It aims to:

• Prevent user confusion
• Communicate the reason for the absence of content
• Provide actionable next steps or suggestions
• Maintain a positive user experience

#Examples

An EmptyState typically includes the following elements:

• Illustration: A visual cue that helps convey the state's meaning (success, reassurance, initiation, promotion, etc.).
• Heading (Optional): A brief, clear title summarizing the state (e.g., "No issues," "No search results"). Can be omitted to display only plain text via the description prop, which is useful for accessibility when heading semantics are not appropriate.
• Description (Optional): Additional context or instructions to guide the user (e.g., "You have not resolved any issues yet." or "Create key metrics to track how your visitors complete key activities on your site.").
• Call to Action (Optional): A button or link prompting the user to take a specific action (e.g., "View all issues," "Create key metric").

#Default

This component is used to show an empty state inside of other components. The component has the required prop type and optional props heading and description. For accessibility reasons, you can omit the heading and use only the description to display plain text without heading semantics. The different kinds of empty state types and the related illustrations are:

• Success: Indicates a successful completion of a task. (IllustrationSuccess)
• Reassure: Provides comfort and reassurance during a wait or lack of content. (IllustrationReassure)
• Initiate: Prompts the user to begin an action or process. (IllustrationInitiate)
• Promote: Encourages the user to explore specific features or content. (IllustrationPromote)

All the illustrations used by this component can be seen on the Illustrations overview page.

No issues

You've resolved all issues on this site - well done!

CodeHTML output

Theme: agentic-ai-2025

Settings

<EmptyState type="success" heading="No issues" description="You've resolved all issues on this site - well done!" />

#Description only (no heading)

For accessibility reasons, you can omit the heading and use only the description to display plain text without heading semantics. This is useful when the text should not introduce a new section of content, such as in table empty states.

No data to display

CodeHTML output

Theme: agentic-ai-2025

Settings

<EmptyState type="reassure" description="No data to display" />

#With markdown

You can use Markdown formatting for the description prop by using the Markdown component.

No issues

This is a markdown string, it contains

• A short list
• with an emphasized word
• and a link

CodeHTML output

Theme: agentic-ai-2025

Settings

const md = `This is a markdown string, it contains - A short list - with an *emphasized* word - and a [link](https://www.siteimprove.com)`; return <EmptyState type="success" heading="No issues" description={<Markdown>{md}</Markdown>} />;

#With link

You can add an optional link to the component or an optional button. Not both.

No resolved issues

You have not resolved any issues yet.

See all issues ↗→

CodeHTML output

Theme: agentic-ai-2025

Settings

<EmptyState type="reassure" heading="No resolved issues" description="You have not resolved any issues yet." link={{ href: "https://siteimprove.com", text: "See all issues" }} />

#With button

You can add an optional button to the component or an optional link. Not both.

No key metrics

Create key metrics to track how your visitors complete key activities on your site.

Create key metric

CodeHTML output

Theme: agentic-ai-2025

Settings

<EmptyState type="initiate" heading="No key metrics" description="Create key metrics to track how your visitors complete key activities on your site." button={{ text: "Create key metric", onClick: () => console.log("clicked") }} />

#Properties

Data insights that empower your team

Siteimprove Analytics gives you powerful insights into visitor behavior and website performance, so you can make data-driven decisions across teams.

CodePropsHTML output

Theme: agentic-ai-2025

Settings

Property	Description	Defined	Value
typeRequired	"initiate" | "promote" | "reassure" | "success"The type of empty state	YesNo	successreassureinitiatepromote
headingOptional	stringHeading for the empty state (optional - can use description alone for plain text)	YesNo
levelOptional	"h1" | "h2" | "h3" | "h4" | "h5" | "h6"Heading level	YesNo	h1h2h3h4h5h6
descriptionOptional	| string | elementDescription for the empty state	YesNo
linkOptional	object	YesNo
buttonOptional	object	YesNo
data-observe-keyOptional	stringUnique string, used by external script e.g. for event tracking	YesNo
classNameOptional	stringCustom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	objectStyle object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	numberTab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	functionCallback for onKeyDown event	YesNo
onMouseDownOptional	functionCallback for onMouseDown event	YesNo
onMouseEnterOptional	functionCallback for onMouseEnter event	YesNo
onMouseLeaveOptional	functionCallback for onMouseLeave event	YesNo
onFocusOptional	functionCallback for onFocus event	YesNo
onBlurOptional	functionCallback for onBlur event	YesNo

#Guidelines

#Best practices

#Do not use when

#Accessibility

Explore detailed guidelines for this component: Accessibility Specifications

#Writing